docs: replace RFC copy-paste docstrings with Pythonic docstrings by ykd007 · Pull Request #1385 · collective/icalendar

ykd007 · 2026-05-14T09:48:44Z

Rewrites RFC copy-paste docstrings across Alarm, Component, and Calendar into clean Pythonic format with concise summaries, examples, and see-also references.

Updated (12 properties across 3 files):

Alarm: ACKNOWLEDGED, TRIGGER
Component: DTSTAMP/stamp, LAST_MODIFIED, CREATED
Calendar: calendar_name, description, color, prodid, version, calscale, method, refresh_interval

All 3 files pass py_compile syntax check.

…lective#1244) Rewrote RFC-verbatim docstrings for the following properties: alarm.py: - Alarm.ACKNOWLEDGED: replaced RFC 9074 Purpose/Description wall-of-text with a concise summary, Return, Example and See also sections. - Alarm.TRIGGER: replaced RFC 5545 Purpose/Value-Type verbatim with a clear summary, type info, Example and See also. component.py: - Component.DTSTAMP / stamp: replaced 'RFC 5545: Conformance/Description' block with a Pythonic summary, context note, Example and See also. - Component.LAST_MODIFIED: same pattern - Pythonic summary, Example, See also. - Component.CREATED: same pattern - Pythonic summary, Example, See also. calendar.py: - Calendar.calendar_name: removed Property Parameters/Conformance/Description RFC headings; added See also. - Calendar.description: same cleanup. - Calendar.color: removed Property Parameters/Conformance/Description RFC headings; added CSS3 link reference and See also. - Calendar.prodid: replaced Conformance/Description verbatim with Pythonic summary, Example and See also. - Calendar.version: replaced Purpose RFC text with Pythonic summary + Example. - Calendar.calscale: replaced Conformance/Description/Compatibility with Pythonic summary, RFC 7529 note, Example and See also. - Calendar.method: replaced Description RFC block with Pythonic summary, iTIP/RFC 5546 reference, Example and See also. - Calendar.refresh_interval: replaced Conformance/Description headings with Pythonic summary, updated Raises, added Example and See also.

read-the-docs-community · 2026-05-14T09:49:37Z

Documentation build overview

📚 icalendar | 🛠️ Build #32686814 | 📁 Comparing 68802f9 against latest (66fb3e1)

🔍 Preview build

9 files changed · ± 9 modified

± Modified

stevepiercy · 2026-05-20T06:55:57Z

@ykd007 would you please resolve the merge conflicts by moving your change log entry into the new format that we adopted in 7.1.2, as documented at https://icalendar.readthedocs.io/en/stable/contribute/index.html#change-log-entry-format?

stevepiercy · 2026-05-20T10:19:00Z

@ykd007 would you also edit your PR description from Closes #1244 to See #1244? We don't want to close it until all the docstrings are checked off the list.

stevepiercy

This is phenomenal work! Thank you!

There are some weird prepended and appended docstrings from a parent method that I'd like to see added to this PR, which will improve other docstrings automatically.

The change log needs to be moved, per the release of 7.1.1, and described in https://icalendar.readthedocs.io/en/stable/contribute/index.html#change-log-entry-format.

Other than that, I pretty much had only grammar and style fixes.

stevepiercy · 2026-05-20T08:40:20Z

-    changed in the alarm component. If the value of any "ACKNOWLEDGED" property
-    in the alarm changes and is greater than or equal to the trigger time of the alarm,
-    then clients SHOULD dismiss or cancel any "alert" presented to the calendar user.
+        """The UTC datetime at which this alarm was last sent or acknowledged.


When I looked at the rendered docs, I found that there was a snippet prepended to this docstring. Would you please revise the following:

https://github.com/stevepiercy/icalendar/blob/8c26d2b22ce33c37bd2bfce7997ca240641236ab/src/icalendar/attr.py#L401-L415

Specifically, and possibly wrapped after using make format:

- f"""The {name} property. datetime in UTC + f"""The {name} property with all values converted to a :class:`~datetime.datetime` in UTC. - All values will be converted to a datetime in UTC. +

The two blank lines will ensure proper concatenation with a new paragraph to begin the description of the docstring.

Suggested change

"""The UTC datetime at which this alarm was last sent or acknowledged.

"""This property is the UTC datetime at which this alarm was last sent or acknowledged as defined in :rfc:`9074`.

stevepiercy · 2026-05-20T08:44:59Z

-    then clients SHOULD dismiss or cancel any "alert" presented to the calendar user.
+        """The UTC datetime at which this alarm was last sent or acknowledged.
+
+    Defined in :rfc:`9074`. Setting this property allows calendar clients to


Moved into previous paragraph.

Suggested change

Defined in :rfc:`9074`. Setting this property allows calendar clients to

Setting this property allows calendar clients to

stevepiercy · 2026-05-20T08:46:54Z

+    Defined in :rfc:`9074`. Setting this property allows calendar clients to
+    dismiss or suppress an alarm across multiple devices. Once set to a value
+    greater than or equal to the alarm's computed trigger time, conforming clients
+    will not re-fire the alarm.


Suggested change

will not re-fire the alarm.

will not refire the alarm.

stevepiercy · 2026-05-20T08:50:08Z

+            >>> from icalendar import Alarm
+            >>> alarm = Alarm()
+            >>> alarm.ACKNOWLEDGED = datetime(2024, 1, 15, 10, 0, 0, tzinfo=timezone.utc)
+            >>> alarm.ACKNOWLEDGED  # doctest: +ELLIPSIS


Inline comments don't render. Is the comment necessary?

Suggested change

>>> alarm.ACKNOWLEDGED # doctest: +ELLIPSIS

>>> alarm.ACKNOWLEDGED

stevepiercy · 2026-05-20T08:50:10Z

+            datetime.datetime(2024, 1, 15, 10, 0, tzinfo=...)
+
+    See also:
+        :attr:`TRIGGER` — the time at which the alarm fires.


Suggested change

:attr:`TRIGGER` — the time at which the alarm fires.

:attr:`TRIGGER`, the time at which the alarm fires.

stevepiercy · 2026-05-20T10:26:39Z

+    Analogous to a file's modification timestamp. This property is optional;
+    when absent, :attr:`last_modified` falls back to :attr:`DTSTAMP`.


Suggested change

Analogous to a file's modification timestamp. This property is optional;

when absent, :attr:`last_modified` falls back to :attr:`DTSTAMP`.

It's analogous to a file's modification timestamp. This property is optional.

When it's absent, :attr:`last_modified` falls back to :attr:`DTSTAMP`.

stevepiercy · 2026-05-20T10:27:13Z

+    Analogous to a file's modification timestamp. This property is optional;
+    when absent, :attr:`last_modified` falls back to :attr:`DTSTAMP`.
+
+    Applicable to ``VEVENT``, ``VTODO``, ``VJOURNAL``, and ``VTIMEZONE``


Suggested change

Applicable to ``VEVENT``, ``VTODO``, ``VJOURNAL``, and ``VTIMEZONE``

This property is applicable to ``VEVENT``, ``VTODO``, ``VJOURNAL``, and ``VTIMEZONE``

stevepiercy · 2026-05-20T10:28:18Z

-        store.
+        """The UTC datetime when this calendar component was first created, per :rfc:`5545#section-3.8.7.1`.
+
+    Records when the calendar user agent originally stored the component.


Suggested change

Records when the calendar user agent originally stored the component.

This property records when the calendar user agent originally stored the component.

stevepiercy · 2026-05-20T10:28:36Z

+        """The UTC datetime when this calendar component was first created, per :rfc:`5545#section-3.8.7.1`.
+
+    Records when the calendar user agent originally stored the component.
+    This property is optional; when absent, :attr:`created` falls back to


Suggested change

This property is optional; when absent, :attr:`created` falls back to

This property is optional. When it's absent, :attr:`created` falls back to

stevepiercy · 2026-05-20T10:28:50Z

-            The property can be specified once in "VEVENT",
-            "VTODO", or "VJOURNAL" calendar components.  The value MUST be
-            specified as a date with UTC time.
+    Applicable to ``VEVENT``, ``VTODO``, and ``VJOURNAL`` components.


Suggested change

Applicable to ``VEVENT``, ``VTODO``, and ``VJOURNAL`` components.

This property is applicable to ``VEVENT``, ``VTODO``, and ``VJOURNAL`` components.

ykd007 requested review from SashankBhamidi, angatha, niccokunzmann and stevepiercy as code owners May 14, 2026 09:48

ykd007 added 2 commits May 14, 2026 15:26

fix doctests: use ELLIPSIS for tzinfo and str() for vText values

a19e528

add changelog entry for docstring improvements

68802f9

stevepiercy requested changes May 20, 2026

View reviewed changes

	"""The UTC datetime at which this alarm was last sent or acknowledged.
	"""This property is the UTC datetime at which this alarm was last sent or acknowledged as defined in :rfc:`9074`.

	Defined in :rfc:`9074`. Setting this property allows calendar clients to
	Setting this property allows calendar clients to

	>>> alarm.ACKNOWLEDGED # doctest: +ELLIPSIS
	>>> alarm.ACKNOWLEDGED

	:attr:`TRIGGER` — the time at which the alarm fires.
	:attr:`TRIGGER`, the time at which the alarm fires.

		Analogous to a file's modification timestamp. This property is optional;
		when absent, :attr:`last_modified` falls back to :attr:`DTSTAMP`.

	Applicable to ``VEVENT``, ``VTODO``, ``VJOURNAL``, and ``VTIMEZONE``
	This property is applicable to ``VEVENT``, ``VTODO``, ``VJOURNAL``, and ``VTIMEZONE``

	Records when the calendar user agent originally stored the component.
	This property records when the calendar user agent originally stored the component.

	This property is optional; when absent, :attr:`created` falls back to
	This property is optional. When it's absent, :attr:`created` falls back to

	Applicable to ``VEVENT``, ``VTODO``, and ``VJOURNAL`` components.
	This property is applicable to ``VEVENT``, ``VTODO``, and ``VJOURNAL`` components.

Uh oh!

Conversation

ykd007 commented May 14, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

read-the-docs-community Bot commented May 14, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Documentation build overview

Uh oh!

stevepiercy commented May 20, 2026

Uh oh!

stevepiercy commented May 20, 2026

Uh oh!

stevepiercy left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

ykd007 commented May 14, 2026 •

edited

Loading

read-the-docs-community Bot commented May 14, 2026 •

edited

Loading